Field specifies the field number (from 1 to 255) that will be created in the current window. Once a field is created, it will be referenced by this field number. If a field has been previously created in the current window using the same number, it will be replaced with a new field as specified by the parameters in the NewField procedure. If the current window doesn’t belong to your application, or if no windows are open, NewField does nothing.
Left, top, right, and bottom define a rectangle in local co-ordinates that determines the field’s size and location in the current window. These parameters can be seen as two corners; the upper left-hand corner (left,top) and the bottom right-hand corner (right,bottom). The field must be wide enough for at least 1 character (minimum of 20 pixels). The height of the field should be the same as a font’s height (font height can be determined by calling the GetFontInfo procedure and adding Ascent + Descent + Leading ). In multiple-line fields, the height should be in increments of the font height.
HStr is a string handle and provides a reference to the edit field’s “string.” In actuality, hStr can be a handle to any size block of memory, but it will be treated as a string by Tools Plus, in that the first byte is a length byte and the remainder is the actual string. The string dereferenced by hStr should have a string size that is an even number of characters, with the exception of a Str255 type, and should never be 0. When the edited text is retrieved for validation or saved as the field’s text, a string[31] will be treated as if it is a string[30] (i.e. even string size). The hStr handle is used to make a copy of the edit field’s string for editing purposes. It is also used to automatically display an inactive edit field’s text when a window needs to be refreshed. Each field must have its own string.
TeType indicates two things: [1] if Return is allowed in a field, and [2] if a box is drawn around the field. If Return is allowed, typing the Return key creates a new line in the field. If Return is not allowed, it generates a doKeyDown or doAutoKey event and is handled by your application. In this case, Return may be treated the same way as Tab. If a box is drawn around the field, it will be drawn as a line that is 1 pixel wide, and will be exactly 3 pixels larger than the dimensions specified by left, top, right, and bottom. This complies with the boxes seen around fields in dialog boxes. One reason you may decide not to have a box drawn around your field is to accommodate a large number of small fields in a window. Constants have been defined for this purpose and are listed at the end of this section.
Just specifies if a field is left aligned, right aligned, or centered. Single line fields that are left or right aligned do not use “word wrap.” Instead, the field’s text scrolls to keep the selection in view. Constants have been defined for this purpose and are listed at the end of this section.
Fonts
`````
When a field is first created, the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) are saved for the field. The window’s settings can then be changed without affecting the field. The field’s font, size, and style cannot be changed without recreating the field.
Also see: NewFieldRect, and the FieldLengthLimit procedure to limit the length of editable text.
Note: Tools Plus makes no attempt to control the placement of fields or
to protect them once they have been created. It is the
programmer’s responsibility to ensure that fields are a sufficient
size (at least 1 character wide and high), and that their
placement within the window is reasonable and does not conflict
with other objects. Furthermore, you should not allow your
application’s text and drawing processes to interfere with fields.
Windows with a “size box” should not allow fields to be obscured
or hidden by making the window too small.
CONST {Field types }
teBoxNoCR = 0 {Outlining box is drawn, Return is not }
{ allowed (default) }
teBoxCR = 1 {Outlining box is drawn, Return is }
{ allowed }
teNoBoxNoCR = 2 {No outlining box, Return is not allowed}
teNoBoxCR = 3 {No outlining box, Return is allowed }
NewFieldRect is identical to the NewField procedure, except that it accepts the Bounds rectangle in place of the individual left, top, right and bottom co-ordinates.
Field specifies the field number (from 1 to 255) that is deleted from the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, DeleteField does nothing.
If the field being deleted is the active field then it is deactivated before being deleted. If field was also in an active, modeless window, the Edit menu’s “Undo” item is changed to “Can’t Undo” and is disabled along with the “Cut”, “Copy”, “Paste” and “Clear” items.
Field specifies the field number (from 1 to 255) being activated in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, ActivateField does nothing. If another field is active while ActivateField is called, the previous field is deactivated prior to activating the specified field.
Selection specifies if the field is left-aligned, right-aligned, or centered. Single line fields that are left or right aligned don’t not use “word wrap.” Instead, the field’s text scrolls to keep the selection in view. Below are the three constants that are used to specify a field selection when being activated.
CONST {Field text selection }
teSelectAll =0; {Select all the field’s text }
teSelectStart=1; {Insertion point at beginning of field }
teSelectEnd =2; {Insertion point at end of field }
If the field being activated is in an active, modeless window, the Edit menu’s “Undo” item is changed to “Can’t Undo” and is disabled, while the “Cut”, “Copy”, “Paste” and “Clear” items are enabled/disabled as previously described in this chapter under “The Edit Menu”.
The active field, if one exists in the current window, is deactivated by this routine. If the current window doesn’t belong to your application, or if no windows are open, or if a field is not active, DeactivateField does nothing. Once a field is deactivated, its edited text is discarded and replaced with the field’s string. Therefore, if you want to save the field’s edited text, call GetFieldString and SaveFieldString prior to deactivating the field.
If the deactivated field is in an active, modeless window, the Edit menu’s “Undo” item is changed to “Can’t Undo” and is disabled along with the “Cut”, “Copy”, “Paste” and “Clear” items.
Process a mouse click that has occurred in an inactive field on the active window.
pascal void ClickInField(void);
procedure ClickInField;
When PollSystem reports a doClickField event, it indicates that the user clicked the mouse in an inactive field. If some other field is active when this event is reported, it is necessary to first process the active field before responding to the click (before ClickInField is called). First, call GetFieldString to retrieve the active field’s edited text for validation. If the string cannot be validated, display an appropriate alert box and ignore the doClickField event. If no error occurred, save the edited text as the field’s string by calling SaveFieldString, then process the click by calling ClickInField.
ClickInField deactivates any active field, and activates the field in which the click occurred by placing an insertion point at the click’s location. A double click in the field an/or subsequent dragging is processed automatically as detailed by “Clicking and Tabbing in Fields” earlier in this chapter.
If the activated field is in a modeless window, the Edit menu’s “Undo” item is changed to “Can’t Undo” and is disabled, while the “Cut”, “Copy”, “Paste” and “Clear” items are enabled/disabled as previously described in this chapter under “The Edit Menu”.
Warning: Between the time when the doClickField event is reported and
when ClickInField is called, observe the following rules:
• do not call PollSystem
• do not open or close any windows, including alerts and
dialog
• do not activate any windows
ClickInField depends on working with the same window that
registered the doClickField event, and will not function
properly if PollSystem reports or processes any subsequent
EditString is a copy of the active field’s edited text in the current window. The field’s edited text and string are not changed. Although it is physically possible to type more than 255 characters in a field that is not length limited, only the first 255 characters are significant. The rest are ignored. If the current window doesn’t belong to your application, or if no windows are open, or if a field is not active, GetFieldString returns a null string (string length of 0).
If the field is not length limited, the text retrieved by GetFieldString may be greater in length than the field’s associated string (as specified by the hStr handle when the field was created). If the field is length limited, EditString’s length will never exceed the size limit of the field’s associated string.
GetFieldString is necessary when validating a field’s edited text. For example, if a doKeyDown even reports that the Tab key was pressed, the active field should be validated prior to activating the next field. GetFieldString obtains a copy of the edited text and allows your application to validate the field. If the field cannot be validated, an appropriate alert should be displayed and the doKeyDown event should be ignored. If the field is successfully validated, the edited text should be saved as the field’s associated string by calling the SaveFieldString procedure, then the next field should be activated.
Save the active field’s edited text as the field’s associated string.
pascal void SaveFieldString(void);
procedure SaveFieldString;
SaveFieldString takes a copy of the active field’s edited text and copies it to the field’s associated string. This action occurs in the current window. The field’s edited text is not changed. If the current window doesn’t belong to your application, or if no windows are open, or if a field is not active, SaveFieldString does nothing.
When SaveFieldString is called, several factors determine the length of the string, or number of characters that are saved. Firstly, only the first 255 characters of the edited text are recognized. The rest are ignored. Secondly, the active field’s string handle (hStr) dictates the maximum number of characters that can be saved. The edited text is saved as a string in the memory block dereferenced by hStr. The maximum string length will always be an even number, with the exception of a Str255 type that is 255 characters long. If the field is length limited, the edited text will comply to these constraints by physically preventing the user from typing characters that would exceed the field’s limit.
The function’s value returns the active field number in the current window. If the current window does not belong to your application, or if no windows are open, or if no field is active in the current window, ActiveFieldNumber returns a value of zero (0).
Limit specifies if subsequently created fields will be length limited or not. The boolean constants “on” or “off” may be used.
Length limiting is an enhancement supported by Tools Plus. It prevents a field’s edited text from exceeding a fixed length. This is done by preventing additional characters from being typed once the field has reached its limit, and by truncating text (if necessary) after a “Paste” command is executed. The user is beeped when excess characters are typed instead of accepting the key-strokes.
If a field is length limited, the limit is set to the maximum length of the field’s string (referenced via the hStr handle) as described in the NewField procedure.
A field takes on its limited/unlimited status when it is created by the NewField procedure, depending on FieldLengthLimit’s setting. When FieldLengthLimit(true) has been set, subsequently created fields will be length limited. When FieldLengthLimit(false) is in effect, subsequently created fields will not be length limited.
For the sake of consistency, all fields on a window should either be limited or unlimited. Length limiting works best, in a visual sense, when a mono-spaced (non-proportional) font is used and the field’s width is long enough to contain the maximum number of characters. In this way, the user is limited to the number of characters that are visible in a field.
FieldLengthLimit is set to false when Tools Plus is initialized.
pascal void OffsetField (int Field, int dh, int dv);
procedure OffsetField(Field, dh, dv: INTEGER);
Field specifies the field number (from 1 to 255) that is repositioned in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, OffsetField does nothing.
Dh and dv specify the horizontal and vertical number of pixels by which the field is offset. If dh and dv are positive, the offsetting is to the right and down. If either are negative, offsetting is in the opposite direction.
The OffsetField procedure merely changes the field’s co-ordinates. It does not actually redraw the field at its new location. To do this, the field’s old location must be erased and the new location should be added to the affected window’s update region.
Scrolling fields
````````````````
Your application can create a matrix of fields and treat them as though they were “cells” in a spread-sheet. For example, fields could be aligned to represent columns and rows: Seven rows, each with 3 fields, is a total of 21 fields. In fact, any combination of lines and columns can be used as long as no more than 255 fields are visible at a time.
By scrolling up or down, the user is given the impression that there are actually more lines available than those that are currently visible. The scrolling process is accomplished by the following series of steps.
(1) Shift Lines: Use the toolbox’s ScrollRect procedure to shift the lines to their new position. They should be shifted to the position where they will appear after scrolling.
(2) Stop Window Updating: Freeze the window in its current state and prevent it from being changed. One of the ways to do this is to store a copy of the affected window’s visRgn, then clear the visRgn with the SetEmptyRgn procedure.
(3) Delete Old Fields: Delete fields that have been scrolled out of view. Because the window is frozen, the DeleteField routine will not change the window.
(4) Shift Fields: Shift each remaining field that will still be visible after scrolling. Use OffsetField to shift the fields’ locations to their new positions.
(5) Resume Updating Window: Restore the affected window’s visRgn. Subsequent changes will be immediately visible in the window.
(6) Create New Fields: Create new fields that are now in view due to scrolling.
Note that within the steps outlined above, you will have to decide how your application deals with the active field and its edited text, since it may be scrolled out of view during this process.
Some applications may require that text be pasted directly into a field under your application’s control. An example of this may be an operation that lets the user select a commonly used item from a List Box. The selected item could then be pasted into a field as though the user had typed it. Use this routine judiciously, because indiscriminate pasting can be detrimental to a good user-interface. Text can be pasted into an active or inactive field. After pasting into an active field, the insertion point is placed after the last character of the pasted text, then the Edit menu, if one exists, has its “Undo” item set to “Undo Paste,” thereby allowing the pasting to be undone.
Field specifies the field number (from 1 to 255) into which the text is pasted in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, PasteIntoField does nothing.
Text specifies the string that is pasted into the specified field. If a null string (length of 0) is specified, the field’s affected text is cleared. When pasting into a length limited field, text is pasted one character at a time (although very quickly) and stops if the field is full.
Replace specifies if the text is pasted into the field to replace the currently selected characters, or if the field’s entire contents are replaced with the specified text. With the value of teInsert, only the selected range of characters is replaced. If an insertion point is present, Text is inserted at that point. If Replace has a value of teReplace, the field’s entire text is replaced with the contents of the Text string. When pasting into an inactive field, the field’s contents are replaced regardless of the value of the Replace variable.
CONST {Types of pasting }
teReplace =true {Replace field’s contents with specified}
{ text. }
teInsert =false {Insert specified text at the insertion }
